package com.maun.maun;

import com.maun.exception.MarshalerException;

/**
 * 
 * @author Aleksandra Rogozhnikova, rogoznikova.av@gmail.com
 */
public interface Maun {

    /**
     * Creates a schema which describes the structure of the marshaled objects of the given class.
     *
     * <p>
     * The schema language and form varies depending on the implementation. It is only guaranteed
     * that objects of the class marshaled using the {@link #marshal(Object)} method will
     * correspond to the schema within the implementation's constraints.
     *
     * <p>
     * E.g. if an implementation marshals and saves objects to the relational database, the schema
     * could be a <code>create table</code> definition and the marshaled objects could be
     * <code>insert</code> statements which would be valid for the table defined by {@link 
     * #createSchema(Class)}.
     * 
     * @param classDefinition
     *      Class for which a schema should be generated.
     * @return
     *      Schema describing the given class.
     * @throws MarshalerException 
     *      If creating a schema fails for some reason.
     */
    public String createSchema(
            Class classDefinition)throws MarshalerException;

    /**
     * Initializes the persistent store for the given class.
     *
     * <p>
     * The way the persistent store is initialized and, basically, what the persistent store is, is
     * defined by the implmentation. It is however guaranteed that the store will match the schema
     * created by {@link #createSchema(Class)} (if applicable at all).
     *
     * @param classDefinition
     *      Class for which the persistent store should be initialized.
     * @throws MarshalerException 
     *      If initializing the persistent store fails for some reason.
     */
    public void initSchema (
            Class classDefinition) throws MarshalerException;

    /**
     * Marshals the given object into a string.
     *
     * The way the object is marshaled depends on the implementation, but the marshaled version of
     * the object will match the schema generated by the {@link #createSchema(Class)} method.
     *
     * @param object
     *      Object which should be marshaled.
     * @return
     *      Marshaled version of the object.
     * @throws MarshalerException 
     *      If marshaling the object fails for some reason.
     */
    public String marshal(
            Object object) throws MarshalerException;

    /**
     * Marshals and saves the given object to the persistent store.
     *
     * <p>
     * The way the object is marshaled and saved depends on the implementation, but the marshaled
     * version of the object will match the schema generated by the {@link #createSchema(Class)}
     * method.
     *
     * @param object
     *      Object which should be marshaled and saved to the persistent store.
     * @throws MarshalerException 
     *      If saving the object fails for some reason.
     */
    public void save(
            Object object) throws MarshalerException;

    /**
     * Closes the current Maun implementation instance and frees its resources. Once this method is
     * invoked, all other methods will become non-functional.
     *
     * @throws MarshalerException 
     *      If closing and freeing resources fails for some reason.
     */
    public void close(
            ) throws MarshalerException;
    
}
